home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / include / libpurple / pluginpref.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-04  |  6.9 KB  |  269 lines
  1. /**
  2.  * @file pluginpref.h Plugin Preferences API
  3.  * @ingroup core
  4.  *
  5.  * purple
  6.  *
  7.  * Purple is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  *
  25.  */
  26. #ifndef _PURPLE_PLUGINPREF_H_
  27. #define _PURPLE_PLUGINPREF_H_
  28.  
  29. typedef struct _PurplePluginPrefFrame        PurplePluginPrefFrame;
  30. typedef struct _PurplePluginPref            PurplePluginPref;
  31.  
  32. /**
  33.  * String format for preferences.
  34.  */
  35. typedef enum
  36. {
  37.     PURPLE_STRING_FORMAT_TYPE_NONE      = 0,
  38.     PURPLE_STRING_FORMAT_TYPE_MULTILINE = 1 << 0,
  39.     PURPLE_STRING_FORMAT_TYPE_HTML      = 1 << 1
  40. } PurpleStringFormatType;
  41.  
  42. typedef enum {
  43.     PURPLE_PLUGIN_PREF_NONE,
  44.     PURPLE_PLUGIN_PREF_CHOICE,
  45.     PURPLE_PLUGIN_PREF_INFO,   /**< no-value label */
  46.     PURPLE_PLUGIN_PREF_STRING_FORMAT
  47. } PurplePluginPrefType;
  48.  
  49. #include <glib.h>
  50. #include "prefs.h"
  51.  
  52. #ifdef __cplusplus
  53. extern "C" {
  54. #endif
  55.  
  56. /**************************************************************************/
  57. /** @name Plugin Preference API                                           */
  58. /**************************************************************************/
  59. /*@{*/
  60.  
  61. /**
  62.  * Create a new plugin preference frame
  63.  *
  64.  * @return a new PurplePluginPrefFrame
  65.  */
  66. PurplePluginPrefFrame *purple_plugin_pref_frame_new(void);
  67.  
  68. /**
  69.  * Destroy a plugin preference frame
  70.  *
  71.  * @param frame The plugin frame to destroy
  72.  */
  73. void purple_plugin_pref_frame_destroy(PurplePluginPrefFrame *frame);
  74.  
  75. /**
  76.  * Adds a plugin preference to a plugin preference frame
  77.  *
  78.  * @param frame The plugin frame to add the preference to
  79.  * @param pref  The preference to add to the frame
  80.  */
  81. void purple_plugin_pref_frame_add(PurplePluginPrefFrame *frame, PurplePluginPref *pref);
  82.  
  83. /**
  84.  * Get the plugin preferences from a plugin preference frame
  85.  *
  86.  * @param frame The plugin frame to get the plugin preferences from
  87.  * @return a GList of plugin preferences
  88.  */
  89. GList *purple_plugin_pref_frame_get_prefs(PurplePluginPrefFrame *frame);
  90.  
  91. /**
  92.  * Create a new plugin preference
  93.  *
  94.  * @return a new PurplePluginPref
  95.  */
  96. PurplePluginPref *purple_plugin_pref_new(void);
  97.  
  98. /**
  99.  * Create a new plugin preference with name
  100.  *
  101.  * @param name The name of the pref
  102.  * @return a new PurplePluginPref
  103.  */
  104. PurplePluginPref *purple_plugin_pref_new_with_name(const char *name);
  105.  
  106. /**
  107.  * Create a new plugin preference with label
  108.  *
  109.  * @param label The label to be displayed
  110.  * @return a new PurplePluginPref
  111.  */
  112. PurplePluginPref *purple_plugin_pref_new_with_label(const char *label);
  113.  
  114. /**
  115.  * Create a new plugin preference with name and label
  116.  *
  117.  * @param name  The name of the pref
  118.  * @param label The label to be displayed
  119.  * @return a new PurplePluginPref
  120.  */
  121. PurplePluginPref *purple_plugin_pref_new_with_name_and_label(const char *name, const char *label);
  122.  
  123. /**
  124.  * Destroy a plugin preference
  125.  *
  126.  * @param pref The preference to destroy
  127.  */
  128. void purple_plugin_pref_destroy(PurplePluginPref *pref);
  129.  
  130. /**
  131.  * Set a plugin pref name
  132.  *
  133.  * @param pref The plugin pref
  134.  * @param name The name of the pref
  135.  */
  136. void purple_plugin_pref_set_name(PurplePluginPref *pref, const char *name);
  137.  
  138. /**
  139.  * Get a plugin pref name
  140.  *
  141.  * @param pref The plugin pref
  142.  * @return The name of the pref
  143.  */
  144. const char *purple_plugin_pref_get_name(PurplePluginPref *pref);
  145.  
  146. /**
  147.  * Set a plugin pref label
  148.  *
  149.  * @param pref  The plugin pref
  150.  * @param label The label for the plugin pref
  151.  */
  152. void purple_plugin_pref_set_label(PurplePluginPref *pref, const char *label);
  153.  
  154. /**
  155.  * Get a plugin pref label
  156.  *
  157.  * @param pref The plugin pref
  158.  * @return The label for the plugin pref
  159.  */
  160. const char *purple_plugin_pref_get_label(PurplePluginPref *pref);
  161.  
  162. /**
  163.  * Set the bounds for an integer pref
  164.  *
  165.  * @param pref The plugin pref
  166.  * @param min  The min value
  167.  * @param max  The max value
  168.  */
  169. void purple_plugin_pref_set_bounds(PurplePluginPref *pref, int min, int max);
  170.  
  171. /**
  172.  * Get the bounds for an integer pref
  173.  *
  174.  * @param pref The plugin pref
  175.  * @param min  The min value
  176.  * @param max  The max value
  177.  */
  178. void purple_plugin_pref_get_bounds(PurplePluginPref *pref, int *min, int *max);
  179.  
  180. /**
  181.  * Set the type of a plugin pref
  182.  *
  183.  * @param pref The plugin pref
  184.  * @param type The type
  185.  */
  186. void purple_plugin_pref_set_type(PurplePluginPref *pref, PurplePluginPrefType type);
  187.  
  188. /**
  189.  * Get the type of a plugin pref
  190.  *
  191.  * @param pref The plugin pref
  192.  * @return The type
  193.  */
  194. PurplePluginPrefType purple_plugin_pref_get_type(PurplePluginPref *pref);
  195.  
  196. /**
  197.  * Set the choices for a choices plugin pref
  198.  *
  199.  * @param pref  The plugin pref
  200.  * @param label The label for the choice
  201.  * @param choice  A gpointer of the choice
  202.  */
  203. void purple_plugin_pref_add_choice(PurplePluginPref *pref, const char *label, gpointer choice);
  204.  
  205. /**
  206.  * Get the choices for a choices plugin pref
  207.  *
  208.  * @param pref The plugin pref
  209.  * @return GList of the choices 
  210.  */
  211. GList *purple_plugin_pref_get_choices(PurplePluginPref *pref);
  212.  
  213. /**
  214.  * Set the max length for a string plugin pref
  215.  *
  216.  * @param pref       The plugin pref
  217.  * @param max_length The max length of the string
  218.  */
  219. void purple_plugin_pref_set_max_length(PurplePluginPref *pref, unsigned int max_length);
  220.  
  221. /**
  222.  * Get the max length for a string plugin pref
  223.  *
  224.  * @param pref The plugin pref
  225.  * @return the max length
  226.  */
  227. unsigned int purple_plugin_pref_get_max_length(PurplePluginPref *pref);
  228.  
  229. /**
  230.  * Sets the masking of a string plugin pref
  231.  *
  232.  * @param pref The plugin pref
  233.  * @param mask The value to set
  234.  */
  235. void purple_plugin_pref_set_masked(PurplePluginPref *pref, gboolean mask);
  236.  
  237. /**
  238.  * Gets the masking of a string plugin pref
  239.  *
  240.  * @param pref The plugin pref
  241.  * @return The masking
  242.  */
  243. gboolean purple_plugin_pref_get_masked(PurplePluginPref *pref);
  244.  
  245. /**
  246.  * Sets the format type for a formattable-string plugin pref. You need to set the
  247.  * pref type to PURPLE_PLUGIN_PREF_STRING_FORMAT first before setting the format.
  248.  *
  249.  * @param pref     The plugin pref
  250.  * @param format The format of the string
  251.  */
  252. void purple_plugin_pref_set_format_type(PurplePluginPref *pref, PurpleStringFormatType format);
  253.  
  254. /**
  255.  * Gets the format type of the formattable-string plugin pref.
  256.  *
  257.  * @param pref The plugin pref
  258.  * @return The format of the pref
  259.  */
  260. PurpleStringFormatType purple_plugin_pref_get_format_type(PurplePluginPref *pref);
  261.  
  262. /*@}*/
  263.  
  264. #ifdef __cplusplus
  265. }
  266. #endif
  267.  
  268. #endif /* _PURPLE_PLUGINPREF_H_ */
  269.